<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Pin: Trace version APIs</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Pin
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">Trace version APIs<div class="ingroups"><a class="el" href="group__API__REF.html">Instrumentation API Reference</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga5fe8277b551bc9a3e6d9b516f39729bd"><td class="memItemLeft" align="right" valign="top">VOID&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__TRACE__VERSION.html#ga5fe8277b551bc9a3e6d9b516f39729bd">BBL_SetTargetVersion</a> (BBL bbl, ADDRINT version)</td></tr>
<tr class="separator:ga5fe8277b551bc9a3e6d9b516f39729bd"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga6ff779779ba60c3afb34f701b82a00f5"><td class="memItemLeft" align="right" valign="top">ADDRINT&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__TRACE__VERSION.html#ga6ff779779ba60c3afb34f701b82a00f5">TRACE_Version</a> (<a class="el" href="group__TRACE.html#gafbca42a46e490ff446dd4c8e54ea182a">TRACE</a> trace)</td></tr>
<tr class="separator:ga6ff779779ba60c3afb34f701b82a00f5"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ga6beede470576f50fe68ddc192616b552"><td class="memItemLeft" align="right" valign="top">VOID&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__TRACE__VERSION.html#ga6beede470576f50fe68ddc192616b552">INS_InsertVersionCase</a> (INS ins, <a class="el" href="group__REG.html#ga8f899d7ad1af070aae505a85cc998fa5">REG</a> reg, INT32 case_value, ADDRINT version,...)</td></tr>
<tr class="separator:ga6beede470576f50fe68ddc192616b552"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>APIs to implement multiple types of instrumentation on traces and switch between them. Trace versioning allows the same code to be instrumented multiple times. For example, a trace can have both heavyweight and lightweight instrumentation and Pin can switch between the two while the application is running. See tests in the tools/InstrumentationOrderAndVersion directory for examples that use the versioning API's.</p>
<p>Versions are user-defined integer values. By default, all traces have a version value of 0. Tool writers insert instrumentation that switch the application between different versions values. A trace with version value N only transfers control to successor traces with version value N.</p>
<p>There are 2 ways to switch between versions. By calling <a class="el" href="group__TRACE__VERSION.html#ga5fe8277b551bc9a3e6d9b516f39729bd">BBL_SetTargetVersion</a> on a BBL, all successor BBL's (taken and not taken path) will have the new version. BBL_SetTargetVersion can only be called once for a BBL, but it can be applied to every BBL in a trace, allowing all the exits to have different versions.</p>
<p>In addition to <a class="el" href="group__TRACE__VERSION.html#ga5fe8277b551bc9a3e6d9b516f39729bd">BBL_SetTargetVersion</a>, it is possible to insert a dynamic test to jump to a different version based on the value of a Pin virtual register with <a class="el" href="group__TRACE__VERSION.html#ga6beede470576f50fe68ddc192616b552">INS_InsertVersionCase</a></p>
<p>Instrumentation functions can query which version is being used with <a class="el" href="group__TRACE__VERSION.html#ga6ff779779ba60c3afb34f701b82a00f5">TRACE_Version</a>.</p>
<p>There are some situations where Pin will reset the version value to 0, even if executing a non 0 trace. This may occur after a system call, exception or other unusual control flow. Versioning is intended to enable lightweight instrumentation. We suggest you structure the tool so a non-zero version value is used for lightweight instrumentation and 0 is for heavyweight, but always safe to use instrumentation. </p>
<h2 class="groupheader">Function Documentation</h2>
<a id="ga5fe8277b551bc9a3e6d9b516f39729bd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga5fe8277b551bc9a3e6d9b516f39729bd">&#9670;&nbsp;</a></span>BBL_SetTargetVersion()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">VOID BBL_SetTargetVersion </td>
          <td>(</td>
          <td class="paramtype">BBL&#160;</td>
          <td class="paramname"><em>bbl</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">ADDRINT&#160;</td>
          <td class="paramname"><em>version</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Pin client interfaces for trace versioning</p>
<p>Set the versioning for traces that can be reached from this basic block. Overrides the versioning from previous basic blocks. It is an error to set the versioning for the same basic block more than once.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">bbl</td><td>BBL to mark for versioning </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">version</td><td>make BBL have this version</td></tr>
  </table>
  </dd>
</dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: All<br  />
<b>CPU:</b> All<br  />
</dd></dl>

</div>
</div>
<a id="ga6beede470576f50fe68ddc192616b552"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga6beede470576f50fe68ddc192616b552">&#9670;&nbsp;</a></span>INS_InsertVersionCase()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">VOID INS_InsertVersionCase </td>
          <td>(</td>
          <td class="paramtype">INS&#160;</td>
          <td class="paramname"><em>ins</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="group__REG.html#ga8f899d7ad1af070aae505a85cc998fa5">REG</a>&#160;</td>
          <td class="paramname"><em>reg</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">INT32&#160;</td>
          <td class="paramname"><em>case_value</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">ADDRINT&#160;</td>
          <td class="paramname"><em>version</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">&#160;</td>
          <td class="paramname"><em>...</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Insert a dynamic test to switch between versions before <em>ins</em>. If the value in <em>reg</em> matches <em>case_value</em>, then continue execution at <em>ins</em> with version <em>version</em>. Switching to a new version will cause execution to continue at a new trace starting with <em>ins</em>. This API can be called multiple times for the same instruction, creating a switch/case construct to select the version.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">ins</td><td>Insert case test before this instruction </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">reg</td><td>Virtual register used to select case. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">case_value</td><td>Go to new version if reg contains case_value </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">version</td><td>New version to use </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">...</td><td>List of additional arguments (see <a class="el" href="group__INST__ARGS.html#ga089c27ca15e9ff139dd3a3f8a6f8451d">IARG_TYPE</a>), terminated with IARG_END. Currently, only IARG_CALL_ORDER is supported. For more information, see <a class="el" href="group__INST__ARGS.html#ga3d1d5f6805cb16d00bce441290ca2212">CALL_ORDER</a>.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: All<br  />
<b>CPU:</b> IA-32 and Intel(R) 64 architectures<br  />
</dd></dl>

</div>
</div>
<a id="ga6ff779779ba60c3afb34f701b82a00f5"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ga6ff779779ba60c3afb34f701b82a00f5">&#9670;&nbsp;</a></span>TRACE_Version()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ADDRINT TRACE_Version </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__TRACE.html#gafbca42a46e490ff446dd4c8e54ea182a">TRACE</a>&#160;</td>
          <td class="paramname"><em>trace</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the version for this trace. See <a class="el" href="group__TRACE__VERSION.html#ga5fe8277b551bc9a3e6d9b516f39729bd">BBL_SetTargetVersion</a></p>
<dl class="section user"><dt>Availability:</dt><dd><b>Mode:</b> JIT<br  />
<b>O/S</b>: All<br  />
<b>CPU:</b> All<br  />
</dd></dl>

</div>
</div>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by &#160;<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.17
</small></address>
</body>
</html>
